fix(dev): detect local postgres during setup - #4621

Summary

Adds an early setup check for a local PostgreSQL server already listening on the configured Postgres port.

This prevents just setup from continuing when migrations could connect to a local PostgreSQL instance instead of the Docker-managed buzz-postgres container.

Problem

When a local PostgreSQL service is listening on port 5432, Docker can still report the Buzz PostgreSQL container as healthy.

However, the migration command connects through localhost:5432. On affected machines, that connection may reach the local PostgreSQL server instead of the Buzz container.

This can produce a misleading error such as:

role "buzz" does not exist

Changes

• Added a PostgreSQL port-conflict preflight check to scripts/dev-setup.sh.
• Detects local postgres and postmaster processes listening on ${PGPORT:-5432}.
• De-duplicates processes that appear under both IPv4 and IPv6.
• Stops setup before services and migrations continue.
• Prints an actionable explanation describing the conflict and how to resolve it.

This change does not modify Docker port mappings or add configurable port support.

Testing

Local PostgreSQL running

Started a Homebrew PostgreSQL 16 service on port 5432 while the Buzz PostgreSQL container was also running.

Verified that just setup stopped immediately with:

A local PostgreSQL server is already listening on port 5432: postgres(pid=...)
Buzz migrations may connect to that server instead of the Docker-managed buzz-postgres container.
Stop the local PostgreSQL service, or configure Buzz to use a different Postgres host port.

Verified that database migrations were not started.

Local PostgreSQL stopped

Stopped the Homebrew PostgreSQL service and confirmed that only Docker was listening on port 5432.

Verified that just setup completed successfully, including:

• database migrations
• local community seeding
• dependency installation
• Git hook installation

Static checks

bash -n scripts/dev-setup.sh
git diff --check

Both checks passed.